Archive Magazine CD 1995/Archive Magazine CD 1995.iso/discs/pipeline/abacus/p_line/Custom01/ReadMe

Text File | 1992-08-14 | 15.1 KB | 286 lines

%OP%VS4.13 (28-Apr-92), Gerald L Fitton, R4000 5966 9904 9938
%OP%DP0
%OP%IRY
%OP%PL0
%OP%HM0
%OP%FM0
%OP%BM0
%OP%LM4
%OP%FX160
%OP%FY160
%OP%FS10000
%OP%PT1
%OP%PDPipeLine
%OP%WC1022,2258,184,1748,0,0,0,0
%CO:A,72,72%
%C%Custom Functions from the Beginning - Part 1
%C%by Gerald L Fitton
Keywords:
4ProL Custom Function Introduction Parameter Sequence Fitton

Introduction to '4ProL'
This is the first tutorial article of a series which, I hope, will help
you to get to grips with one of the new features of PipeDream 4, custom
functions.  If you wish to use these custom functions then you need to
learn the PipeDream 4 custom function programming language which, at
present, doesn't have a name.  I shall call it '4ProL'.  I'm not sure
of the best pronunciation but 'four-prol' seems OK to me!  When Robert
Macmillan reads this I am sure that he will offer a small prize for the
best name (and pronunciation) of PD4's programming language.

One thing to clear up from the start.  Custom functions are different
from command files.  Custom functions did not exist in PipeDream 3 but
command files (called 'macros') did.  Command files consist of a
sequence of PipeDream commands such as <Ctrl CGS> (Cursor Goto Slot)
and <Ctrl BM> (Block Move); they can be used to add or delete rows and
columns, even to load and save documents.  Custom functions can not be
used to move blocks around within a document nor indeed to change the
'shape' of a document in any way.  However, what you can do with custom
functions is to process the data which already exists within the slots
of a document (or within a set of documents) in more intricate ways
than can be done simply with the 'standard' functions provided.  Just
like any standard function such as (A1 + A2) or the more complex
lookup(A1,B1B10,C1C10), a custom function is 'called' from a slot and
the 'result' of executing the function is returned to the slot from
which it is called.

Calling custom functions
Let's have a look at a custom function at work.  Double click on the
file [AddOne] and you will find that you load to the screen not only
[AddOne] but a dependent document which I have called [c_AddOne]
containing a simple, two line, custom function.  I have deliberately
limited the width of [c_AddOne] to 72 characters so that it will fit
across a mode 12 screen.

You can use any valid filing system file name for a custom function
document but, so that I can recognise which PipeDream files are
'ordinary' documents and which are custom function documents, I have
prefixed all my custom function documents with c_ (a lower case c
followed by an underline).  I suggest that you follow this convention;
it is recommended not only by me but by Colton Software as well.

Because PipeDream 4 saves the position of a PipeDream document on the
screen and the position of the cursor within the document, what you
should find is that [AddOne] is visible and alive (a yellow top bar)
with the cursor in slot [AddOne]A3.  If not then position the pointer
on the number in [AddOne]A3 (it should be the number 2 unless you've
modified the file) and click the mouse select (left) button.  You
should see the same number in the formula line (at the top of the
document just to the right of the cross and tick).  Tap some other
number, say 9, and then tap <Return>.  If all goes well then, besides
[AddOne]A3 changing to 9, the number in [AddOne]B3 will change to 10.

The custom function 'called' from [AddOne]B3 is not a spectacular
custom function.  The 'result' returned to the slot [AddOne]B3 is
(A3 + 1), one more than the number in the slot [AddOne]A3.  Change the
value in [AddOne]A3 a few times and convince yourself that the value in
[AddOne]B3 is always 1 more than the value in [AddOne]A3.

Now let's have a look at the content of slot [AddOne]B3.  Place the
pointer over [AddOne]B3 and click select.  The formula line does not
show the simple, non custom function way of adding 1 which would be
(A3 + 1); instead it shows the formula used to 'call' the custom
function, namely [c_AddOne]one_more_than(A3).  Before looking at the
custom function document, [c_AddOne], let's have a look at the formula
used to call the custom function in more detail.

The 'calling' formula is in three parts:

The first part - [c_AddOne] - is the name of the dependent document
which contains the custom function.  A custom function document such as
[c_AddOne] can contain more than one custom function.  Indeed, it is
desirable to 'split up' large, exotic custom functions into a set of
smaller custom functions (stored within the same 'c_' document) in the
same way that it is usually desirable to split up a long program
written in BASIC into more easily digested PROCs and FNs.

The second part - one_more_than - is the name of the custom function
within [c_AddOne].  If you look at slot A7 of the document [c_AddOne]
you will see that - one_more_than -, the name of the custom function,
appears after the word 'function'.  Another convention which I
recommend to you is that the names of custom functions should be
totally in lower case (no capitals).  The reason is that lower case and
upper case function names are equivalent (unlike BASIC procedures) and
PipeDream converts upper case letters in the custom function names to
lower case anyway!

The third part - (A3) - is the single piece of data which is passed to
the custom function for processing.  To be more accurate, [AddOne]A3 is
the slotref of the data passed to [c_AddOne] for processing.  The data
passed to a custom function this way is called a 'parameter'.  A
parameter is a 'sort of' variable which has a 'fixed' value within the
custom function but can be varied outside the custom function.  As we
shall see in a later tutorial, it is possible to pass more than one
parameter to a custom function.  You can pass as many different
parameters as you wish to a custom function but, if you want to pass a
large amount of data, rather than use many parameters (a rather
cumbersome method), it is better to pass a range of slots or an array
as one single parameter.

Returning the result
'Calling' the custom function - [c_AddOne]one_more_than(A3) - from slot
[AddOne]B3 returns the result of the processing to the slot from which
it was called, [AddOne]B3.  Although the result can be returned to only
a single slot this does not mean that you can return only one value
from a custom function!  You can return many values to one slot by
returning an array to the calling slot.  This array can then be
expanded using set_value(range,slotref) where 'slotref' contains the
array (and the calling function) and where 'range' is the range of
slots containing the expanded array.  We shall return to examples of
this tactic in a later tutorial.

Programming in general
Before we look at the custom function [c_AddOne] in detail I am going
to digress and discuss programming from a broader point of view.

Perhaps you are familiar with writing short programs in BASIC.  That
may help or it may not!  Perhaps you write 'well written' or perhaps
'badly written' BASIC programs.  Both types usually work most of the
time; both types sometimes fail.  The difference between the two is
often apparent only when you want to 'debug', modify, improve or extend
the program you (or maybe someone else) has written.  Those programs
which I class as 'good' are usually easier to 'debug' if they don't
work first time and easier for others to modify if they wish to extend
or improve them.  Short 'bad' programs can usually be written in a much
shorter time so too many programmers with no formal training pick up
some bad habits when they start programming.  This is particularly true
if they write short 'bad' programs which work.  Early 'bad' habits
learnt that way are often the most difficult to break.

Some languages encourage 'good' programming.  Others permit 'bad' or
even 'very bad' programming.  I think I would put '4ProL' in the
'fairly good' category!

Programming in '4ProL'
Custom function documents such as - [c_AddOne] - contain custom
functions such as - one_more_than - which are written in the
programming language I have called '4ProL'.  A custom function is a set
of instructions which is designed to process similar data in a similar
way.  No matter what the actual value of the data, the same set of
instructions are followed.  For example, in the case of
- one_more_than - the data passed to it is a parameter representing a
single number such as 2 and the pair of instructions which make up
- one_more_than - process the number represented by the parameter by
adding 1 and returning the result.

Whatever the number which is passed as a parameter to - one_more_than -
the 'result' returned is one more than the original number.  That
original number is represented within the custom function as the
parameter "parameter".  Custom functions are written so that they can
and most often do operate on variables (symbols representing any
similar piece of data) rather than sets of instructions which process
data directly.

There are many ways of classifying variables; one is by the way in
which they retain or lose their identity when the overall program is
broken down into smaller units.  Using this classification a parameter
is a 'sort of' variable; there are two more sorts called 'local' and
'global' variables which I shall introduce in another tutorial.

Within all but the simplest programming languages the manner of
processing the data (best included as variables) is based on four
concepts.  We shall study these concepts under the headings:
"Sequence", "Repetition" (such as "for - next" loops), "Decision" (such
as "if - then" statements) and "Interrupt" (which will include the use
of the '4ProL' commands - input - and - alert).  I shall limit this
tutorial to a discussion of "Sequence" and the use of a parameter.
In later tutorials we shall discover other sorts of variables as well
as the concepts of "Repetition", "Decision" and "Interrupt".

Sequence
This topic is concerned with the order in which the commands are
executed.  Every sequence must have a start and a finish.

In a large number of spreadsheets you must choose whether to
recalculate along the rows (one at a time, starting at the top and
running from left to right along each row) or down the columns (one at
a time starting with the left most column and working down each column
from top to bottom).  In PipeDream 4 recalculation takes place in an
order which is called "natural".  Here is not the place to explain in
detail what is meant by "natural"; essentially, with "natural"
recalculation, every slot can be regarded as part of a chain and the
calculation proceeds along the chain in such a way that slots which
depend on other slots are processed last no matter where they are
located within the document.  When a slot is changed in PipeDream 4
only those chains which are affected are recalculated.

In a PipeDream 4 custom function the default sequence is that commands
are executed, one at a time, down a single column.  The start is
identified by the command - function - and the end is identified by the
command - result.

The custom function
What we haven't looked at yet is the custom function itself to see how
it adds one to the parameter and returns the 'result'.  To do this we
must bring the custom function - [c_AddOne]one_more_than - into view.

Let's look at the commands in detail and see how they process data.

Row 7 - ...function("one_more_than","parameter:number")
In this custom function the '4ProL' command - ...function - has two
arguments.  The first argument is the name of the custom function,
- "one_more_than" - note that the name is included in inverted commas.
The second argument is the one and only parameter passed to the
function.  The name of the one parameter passed to - [c_AddOne] - is
- parameter - and its 'type' has been declared (after the colon) as a
number.  Because of this declaration, if you try to pass anything other
than a number to this function then an error will be generated.  You do
not have to declare the type of variable if you want to pass a number
sometimes and, say, a string on another occasion.

Try typing Fred (without and then with inverted commas) into [AddOne]A3
and you will find that the error message - String not expected - is
returned to slot [AddOne]B3.  You will find the error message
foreshortened in the body of the [AddOne] document.  If you want to
read the full error message then click the pointer in [AddOne]B3, then
on the formula button (the italic f just to the right of the
PipeDream 4 logo) and finally run the pointer through the first menu
option - Slot 'B3' - Slot value - and you will see the full error
message displayed.  This technique is particularly useful when long
error messages are generated.

Row 8 - ...result(@parameter+1)
The command - ...result - terminates the sequence of commands and
returns a value to the slot from which it was called, [AddOne]B3.  Note
the @@ sign preceding the word - parameter - and the inverted commas
have gone.  The @@ sign 'goes with' the word - parameter - try
...return(1+@@parameter), it gives the same result.

Try changing ...return(@parameter+1) to ...return(@parameter+2).  You
have to do this in the formula line of [c_AddOne].  Even when you have
modified the custom function, the number 3 in the slot [AddOne]B3 does
not change.  To make that change, and indeed if you want to check
whether you have introduced any 'bugs' (errors in programming) in
[c_AddOne] you must 'run' the custom function by 'calling' it again
from the document [AddOne].  The simplest way of doing this is to place
the cursor in slot [AddOne]B3, then move the pointer to the formula
line and click on [c_AddOne]one_more_than(A3).  Finally, click on the
green tick to the left of the formula line; when you click on the green
tick the custom function will be called and the new 'result' will be
returned to [AddOne]B3.

Over to you now
As your first exercise in writing custom functions try to recreate the
pair of documents, [AddOne] and [c_AddOne].  Only when you have
succeeded are you ready to continue!  If you have problems then reload
my [c_AddOne] and type <Ctrl O> to check that you have suitable default
options in your custom function document.  In particular it is
advisable to set the <Ctrl O> - New slot format - to Numbers.
Secondly, note that the three dots which precede the word - function -
appear automatically in slot [c_AddOne]A7 and do not appear in the
formula line.  You do not type the three dots anywhere; just type the
expression - function("one_more_than","parameter:number") - into a
"number" slot and tap <Return>!  In case you really get stuck I have
included in this directory a file call [CustomFn] which you might like
to load and then save with <Ctrl FI> as a custom function template.

Summary
A custom function is a sequence of commands which start with a
- function - command and end with a - result - command.  Once there is
a custom function within a document then the whole document is a custom
function document.  Custom function documents behave differently from
'ordinary' documents - but they do not have a different file type!

The next tutorial
The next tutorial of this series is in the Custom02 directory.